home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / opussdk / docs / requesters.doc < prev    next >
Text File  |  1996-09-05  |  10KB  |  258 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/AsyncRequest
  4. dopus5.library/OpenStatusWindow
  5. dopus5.library/SelectionList
  6. dopus5.library/SetStatusText
  7. dopus5.library/AsyncRequest                       dopus5.library/AsyncRequest
  8.  
  9.     NAME
  10.         AsyncRequest - display a requester
  11.  
  12.     SYNOPSIS
  13.         AsyncRequest(ipc, type, window, callback, data, tags)
  14.                       A0   D0     A1       A2      A3    D1
  15.  
  16.         long AsyncRequest(IPCData *, long, struct Window *,
  17.                           REF_CALLBACK, APTR, struct TagItem *);
  18.  
  19.         long AsyncRequestTags(IPCData *, long, struct Window *,
  20.                               REF_CALLBACK, APTR, Tag, ...);
  21.  
  22.     FUNCTION
  23.         Displays requesters of different types. The name of this function
  24.         is slightly misleading, as the routine itself is not asynchronous.
  25.         However, the requester is launched by a separate process, which makes
  26.         it possible for you to provide a callback function that can handle
  27.         refreshing of a window while the requester is displayed. There are
  28.         currently two types of requesters defined:
  29.  
  30.  
  31.         REQTYPE_FILE
  32.  
  33.         This opens an ASL file requester. The FileRequester itself is defined
  34.         by you; this routine simples opens it with a separate process,
  35.         providing asynchronicity. The only value tag for this requester type
  36.         is AR_Requester, with which you specify the address of a file
  37.         requester structure obtained via AllocAslRequest().
  38.  
  39.  
  40.         REQTYPE_SIMPLE
  41.  
  42.         This displays a simple text requester to the user. There are several
  43.         control tags for this requester type which give you great control
  44.         over the appearance of the requester :
  45.  
  46.             AR_Window (struct Window *)
  47.  
  48.             Use this to specify a parent window for the requester. The
  49.             requester will appear centered over this window (overrides
  50.             AR_Screen)
  51.  
  52.             AR_Screen (struct Screen *)
  53.  
  54.             Use this to specify a parent screen for the requester. The
  55.             requester will appear centered in the screen.
  56.  
  57.             AR_Title (char *)
  58.  
  59.             The requester title. This is displayed in the title bar of the
  60.             requester window. If not specified, this value defaults to
  61.             "Directory Opus Request".
  62.  
  63.             AR_Message (char *)
  64.  
  65.             The requester message. This is the text displayed in the main
  66.             body of the requester. Use a \n character to represent a linefeed.
  67.  
  68.             AR_Button (char *)
  69.  
  70.             This tag allows you to define a button for the requester. You
  71.             can use this tag multiple times.
  72.  
  73.             AR_ButtonCode (long)
  74.  
  75.             Specifies the ID code for the previous AR_Button tag. By default,
  76.             buttons are numbered 1, 2, 3, ... in the order they appear in the
  77.             tag list. This tag allows you to change the ID codes, and
  78.             therefore the result code from the AsyncRequest() function.
  79.  
  80.             AR_Buffer (char *)
  81.  
  82.             If you want a string gadget to be displayed in the requester,
  83.             specify this tag with a pointer to a string buffer.
  84.  
  85.             AR_BufLen (long)
  86.  
  87.             If a buffer was specified with AR_Buffer, you must also supply
  88.             this tag to set the size of the buffer.
  89.  
  90.             AR_History (Att_List *)
  91.  
  92.             Points to an Att_List which contains the history list for this
  93.             gadget. If supplied, the user will be able to press the cursor
  94.             up and down keys to access the history. See the docs on
  95.             GetEditHook() for more information.
  96.  
  97.             AR_CheckMark (char *)
  98.  
  99.             If you want a check mark gadget to appear in the requester,
  100.             specify this as a pointer to the text for the gadget.
  101.  
  102.             AR_CheckPtr (short *)
  103.  
  104.             If you specify the AR_CheckMark tag, you must also supply this
  105.             tag. ti_Data is a pointer to a short variable which will receive
  106.             the state of the checkmark gadget when the requester is closed.
  107.  
  108.             AR_Flags (ULONG)
  109.  
  110.             Control flags.
  111.  
  112.         The control flags for the AR_Flags tag are :
  113.  
  114.             SRF_LONGINT     - the string gadget is an integer field
  115.             SRF_CENTJUST    - center-justify the string gadget
  116.             SRF_RIGHTJUST   - right-justify the string gadget
  117.             SRF_PATH_FILTER - filter path characters from string field
  118.             SRF_SECURE      - set for secure password field
  119.             SRF_HISTORY     - set if supplying the AR_History tag
  120.             SRF_CHECKMARK   - set if supplying the AR_CheckMark tag
  121.             SRF_MOUSE_POS   - center requester over mouse pointer
  122.  
  123.  
  124.         The callback function is a function that you define to handle the
  125.         situation when the parent window needs to be refreshed. If the parent
  126.         window is simplerefresh, you should provide this function. The function
  127.         has the following prototype:
  128.  
  129.             void __asm refresh_callback(    register __d0 ULONG type,
  130.                                             register __a0 struct Window *window,
  131.                                             register __a1 ULONG data )
  132.  
  133.         The routine will be called whenever the parent window needs to be
  134.         refreshed. 'type' is the IDCMP message type; usually
  135.         IDCMP_REFRESHWINDOW. 'window' is a pointer to the parent window, and
  136.         'data' is the data value passed to the AsyncRequest() function.
  137.  
  138.     INPUTS
  139.         ipc      - your process' IPCData pointer
  140.         type     - type of requester to display
  141.         window   - parent window for requester
  142.         callback - your callback function
  143.         data     - data that is passed to the callback
  144.         tags     - control tags
  145.  
  146.     RESULT
  147.         Returns the result from the requester. Returns 0 if the requester
  148.         could not be displayed.
  149.  
  150.     NOTES
  151.         For a REQTYPE_SIMPLE requester, the default gadget IDs are (from
  152.         left to right), 1, 2, 3 ... 0. The right-most gadget is defined as
  153.         0 to act as a "cancel" gadget. Therefore, in a simple "Ok", "Cancel"
  154.         requester, "Ok" returns 1 (or TRUE) and "Cancel" returns 0 (or FALSE).
  155.  
  156.     SEE ALSO
  157.         asl.library/AllocAslRequest(), GetEditHook()
  158.  
  159. dopus5.library/OpenStatusWindow               dopus5.library/OpenStatusWindow
  160.  
  161.     NAME
  162.         OpenStatusWindow - open a status window
  163.  
  164.     SYNOPSIS
  165.         OpenStatusWindow(title, text, screen, flags, unused)
  166.                            A0    A1      A2     D0     D1
  167.  
  168.         struct Window *OpenStatusWindow(char *, char *, struct Screen *, 
  169.                                         ULONG, long);
  170.  
  171.     FUNCTION
  172.         A status window is kind of like a "dumb" progress window; it has
  173.         the ability to display a single line of text.
  174.  
  175.     INPUTS
  176.         title  - status window title
  177.         text   - initial text to display
  178.         screen - screen to open on
  179.         flags  - set to 0
  180.         unused - set to 0
  181.  
  182.     RESULT
  183.         Returns a pointer to the new window. To close the status window,
  184.         call CloseConfigWindow() on it.
  185.  
  186.     SEE ALSO
  187.         SetStatusText(), CloseConfigWindow()
  188.  
  189. dopus5.library/SelectionList                     dopus5.library/SelectionList
  190.  
  191.     NAME
  192.         SelectionList - display a list in a requester
  193.  
  194.     SYNOPSIS
  195.         SelectionList(  list, window, screen,
  196.                         title, initialsel, flags,
  197.                         buffer, okay_txt, cancel_txt )
  198.  
  199.         short SelectionList(    Att_List *, struct Window *, struct Screen *,
  200.                                 char *, short, ULONG,
  201.                                 char *, char *, char * );
  202.  
  203.     FUNCTION
  204.         This routine displays a requester containing a listview gadget,
  205.         prompting the user to select an item from the list. The requester
  206.         can optionally have a directory field, which allows the user to open
  207.         an ASL file requester to locate a directory that is not in the list.
  208.  
  209.     INPUTS
  210.         list       - Att_List to display (the name of each node is displayed)
  211.         window     - parent window
  212.         screen     - screen to open on if no window specified
  213.         title      - title of requester
  214.         initialsel - initially selected item, or -1 for no selection
  215.         flags      - control flags. Specify SLF_DIR_FIELD to get a directory
  216.                      field
  217.         buffer     - If SLF_DIR_FIELD is specified, this must point to a
  218.                      buffer (256 bytes or greater) to contain the path name
  219.                      chosen by the user
  220.         okay_txt   - text for the "Ok" gadget
  221.         cancel_txt - text for the "Cancel" gadget
  222.  
  223.     RESULT
  224.         Returns the number of the selected item in the list, or -1 if the
  225.         user made no selection. If a directory field was specified with
  226.         SLF_DIR_FIELD, and -1 is returned, you should check the supplied
  227.         buffer to see if it is empty. If not, the user selected a path
  228.         manually.
  229.  
  230.     SEE ALSO
  231.         Att_NewList()
  232.  
  233. dopus5.library/SetStatusText                     dopus5.library/SetStatusText
  234.  
  235.     NAME
  236.         SetStatusText - change text in a status window
  237.  
  238.     SYNOPSIS
  239.         SetStatusText(window, text)
  240.                         A0     A1
  241.  
  242.         void SetStatusText(struct Window *, char *);
  243.  
  244.     FUNCTION
  245.         Changes the text displayed in the supplied status window.
  246.  
  247.     INPUTS
  248.         window - status window
  249.         text   - new text to display
  250.  
  251.     RESULT
  252.         The text is displayed immediately. Do NOT call this function on a
  253.         window other than one returned by the OpenStatusWindow() call.
  254.  
  255.     SEE ALSO
  256.         OpenStatusWindow()
  257.  
  258.